MkCliDoc

Node for showing documentation for click / typer CLI apps.¶

ExamplesDocStringsBase classes⋔ Inheritance diagramNodeFileCode

Example: MkDocs-MkNodes CLI¶

Jinja

{{ "mkdocs_mknodes.cli:cli" | MkCliDoc }}

Python

MkCliDoc('mkdocs_mknodes.cli:cli')

RenderedMarkdownHtmlRepr tree

MkNodes¶

🚀🚀🚀 MkNodes CLI interface. Build websites from command line! 🚀🚀🚀

Check out https://phil65.github.io/mkdocs-mknodes/ !

mknodes [OPTIONS] COMMAND [ARGS]...

`--install-completion`¶

Flag Install completion for the current shell.

`--show-completion`¶

Flag Show completion for the current shell, to copy it or customize the installation.

`--help`¶

Flag Show this message and exit.

## MkNodes

🚀🚀🚀 MkNodes CLI interface. Build websites from command line! 🚀🚀🚀

Check out https://phil65.github.io/mkdocs-mknodes/ !

```` {.python }
mknodes [OPTIONS] COMMAND [ARGS]...
````

### `--install-completion`

<span class="md-typeset mdx-badge">
  <span class="mdx-badge__icon">:mdi-flag:</span>
  <span class="mdx-badge__text">Flag</span>
</span>
Install completion for the current shell.


### `--show-completion`

<span class="md-typeset mdx-badge">
  <span class="mdx-badge__icon">:mdi-flag:</span>
  <span class="mdx-badge__text">Flag</span>
</span>
Show completion for the current shell, to copy it or customize the installation.


### `--help`

<span class="md-typeset mdx-badge">
  <span class="mdx-badge__icon">:mdi-flag:</span>
  <span class="mdx-badge__text">Flag</span>
</span>
Show this message and exit.

<h2 id="mknodes">MkNodes</h2>
<p>🚀🚀🚀 MkNodes CLI interface. Build websites from command line! 🚀🚀🚀</p>
<p>Check out <a href="https://phil65.github.io/mkdocs-mknodes/">https://phil65.github.io/mkdocs-mknodes/</a> !</p>
<div class="highlight"><pre><span></span><code><span class="n">mknodes</span> <span class="p">[</span><span class="n">OPTIONS</span><span class="p">]</span> <span class="n">COMMAND</span> <span class="p">[</span><span class="n">ARGS</span><span class="p">]</span><span class="o">...</span>
</code></pre></div>
<h3 id="-install-completion"><code>--install-completion</code></h3>
<p><span class="md-typeset mdx-badge">
  <span class="mdx-badge__icon"><span class="twemoji"><svg xmlns="http://www.w3.org/2000/svg" width="1em" height="1em" viewBox="0 0 24 24"><path fill="currentColor" d="M14.4 6L14 4H5v17h2v-7h5.6l.4 2h7V6z"/></svg></span></span>
  <span class="mdx-badge__text">Flag</span>
</span>
Install completion for the current shell.</p>
<h3 id="-show-completion"><code>--show-completion</code></h3>
<p><span class="md-typeset mdx-badge">
  <span class="mdx-badge__icon"><span class="twemoji"><svg xmlns="http://www.w3.org/2000/svg" width="1em" height="1em" viewBox="0 0 24 24"><path fill="currentColor" d="M14.4 6L14 4H5v17h2v-7h5.6l.4 2h7V6z"/></svg></span></span>
  <span class="mdx-badge__text">Flag</span>
</span>
Show completion for the current shell, to copy it or customize the installation.</p>
<h3 id="-help"><code>--help</code></h3>
<p><span class="md-typeset mdx-badge">
  <span class="mdx-badge__icon"><span class="twemoji"><svg xmlns="http://www.w3.org/2000/svg" width="1em" height="1em" viewBox="0 0 24 24"><path fill="currentColor" d="M14.4 6L14 4H5v17h2v-7h5.6l.4 2h7V6z"/></svg></span></span>
  <span class="mdx-badge__text">Flag</span>
</span>
Show this message and exit.</p>

MkCliDoc
╰── MkHeader('`--help`', level=3)
╰── MkMaterialBadge('mdi:flag', 'Flag')

Example: SubCommand¶

Jinja

{{ "mkdocs_mknodes.cli:cli" | MkCliDoc(prog_name="build") }}

Python

MkCliDoc('mkdocs_mknodes.cli:cli', prog_name='build')

RenderedMarkdownHtmlRepr tree

build¶

Create a MkNodes-based website, locally or remotely.

Runs the build script on given repository (either locally or a hosted one), adapts the config file automatically and creates the HTML website in given site dir.

Further info here: https://phil65.github.io/mkdocs-mknodes/CLI/

mknodes build [OPTIONS]

`--repo-url`, `-r`¶

Repository URL of the target package. Can be remote or local.

`--build-fn`, `-b`¶

Path to the build script. (form: path.to.module:function )

`--site-dir`, `-d`¶

Default: site Path to the folder where the HTML should get written.

`--clone-depth`, `-c`¶

Git clone depth in case repository is remote. Important for changelog generation.

`--config-path`, `-p`¶

Default: mkdocs.yml Path to the config file.

`--theme`, `-t`¶

Default: material Theme to use for the build. Overrides config setting.

`--strict`, `-s`¶

Flag Strict mode (fails on warnings)

`-u`, `--use-directory-urls`¶

Default: True Flag Use directory-style URLs.

`--verbose`, `-v`¶

Flag Enable verbose output. (DEBUG level)

`--quiet`, `-q`¶

Flag Suppress output during build.

`--help`¶

Flag Show this message and exit.

## build

Create a MkNodes-based website, locally or remotely.

Runs the build script on given repository (either locally or a hosted one), adapts
the config file automatically and creates the HTML website in given site dir.

Further info here: https://phil65.github.io/mkdocs-mknodes/CLI/

```` {.python }
mknodes build [OPTIONS]
````

### `--repo-url`, `-r`

Repository URL of the target package. Can be remote or local.


### `--build-fn`, `-b`

Path to the build script. (form: `path.to.module:function` )


### `--site-dir`, `-d`

**Default:** site
Path to the folder where the HTML should get written.


### `--clone-depth`, `-c`

Git clone depth in case repository is remote. Important for changelog generation.


### `--config-path`, `-p`

**Default:** mkdocs.yml
Path to the config file.


### `--theme`, `-t`

**Default:** material
Theme to use for the build. Overrides config setting.


### `--strict`, `-s`

<span class="md-typeset mdx-badge">
  <span class="mdx-badge__icon">:mdi-flag:</span>
  <span class="mdx-badge__text">Flag</span>
</span>
Strict mode (fails on warnings)


### `-u`, `--use-directory-urls`

**Default:** True
<span class="md-typeset mdx-badge">
  <span class="mdx-badge__icon">:mdi-flag:</span>
  <span class="mdx-badge__text">Flag</span>
</span>
Use directory-style URLs.


### `--verbose`, `-v`

<span class="md-typeset mdx-badge">
  <span class="mdx-badge__icon">:mdi-flag:</span>
  <span class="mdx-badge__text">Flag</span>
</span>
Enable verbose output. (`DEBUG` level)


### `--quiet`, `-q`

<span class="md-typeset mdx-badge">
  <span class="mdx-badge__icon">:mdi-flag:</span>
  <span class="mdx-badge__text">Flag</span>
</span>
Suppress output during build.


### `--help`

<span class="md-typeset mdx-badge">
  <span class="mdx-badge__icon">:mdi-flag:</span>
  <span class="mdx-badge__text">Flag</span>
</span>
Show this message and exit.

<h2 id="build">build</h2>
<p>Create a MkNodes-based website, locally or remotely.</p>
<p>Runs the build script on given repository (either locally or a hosted one), adapts
the config file automatically and creates the HTML website in given site dir.</p>
<p>Further info here: <a href="https://phil65.github.io/mkdocs-mknodes/CLI/">https://phil65.github.io/mkdocs-mknodes/CLI/</a></p>
<div class="highlight"><pre><span></span><code><span class="n">mknodes</span> <span class="n">build</span> <span class="p">[</span><span class="n">OPTIONS</span><span class="p">]</span>
</code></pre></div>
<h3 id="-repo-url-r"><code>--repo-url</code>, <code>-r</code></h3>
<p>Repository URL of the target package. Can be remote or local.</p>
<h3 id="-build-fn-b"><code>--build-fn</code>, <code>-b</code></h3>
<p>Path to the build script. (form: <code>path.to.module:function</code> )</p>
<h3 id="-site-dir-d"><code>--site-dir</code>, <code>-d</code></h3>
<p><strong>Default:</strong> site
Path to the folder where the HTML should get written.</p>
<h3 id="-clone-depth-c"><code>--clone-depth</code>, <code>-c</code></h3>
<p>Git clone depth in case repository is remote. Important for changelog generation.</p>
<h3 id="-config-path-p"><code>--config-path</code>, <code>-p</code></h3>
<p><strong>Default:</strong> mkdocs.yml
Path to the config file.</p>
<h3 id="-theme-t"><code>--theme</code>, <code>-t</code></h3>
<p><strong>Default:</strong> material
Theme to use for the build. Overrides config setting.</p>
<h3 id="-strict-s"><code>--strict</code>, <code>-s</code></h3>
<p><span class="md-typeset mdx-badge">
  <span class="mdx-badge__icon"><span class="twemoji"><svg xmlns="http://www.w3.org/2000/svg" width="1em" height="1em" viewBox="0 0 24 24"><path fill="currentColor" d="M14.4 6L14 4H5v17h2v-7h5.6l.4 2h7V6z"/></svg></span></span>
  <span class="mdx-badge__text">Flag</span>
</span>
Strict mode (fails on warnings)</p>
<h3 id="-u-use-directory-urls"><code>-u</code>, <code>--use-directory-urls</code></h3>
<p><strong>Default:</strong> True
<span class="md-typeset mdx-badge">
  <span class="mdx-badge__icon"><span class="twemoji"><svg xmlns="http://www.w3.org/2000/svg" width="1em" height="1em" viewBox="0 0 24 24"><path fill="currentColor" d="M14.4 6L14 4H5v17h2v-7h5.6l.4 2h7V6z"/></svg></span></span>
  <span class="mdx-badge__text">Flag</span>
</span>
Use directory-style URLs.</p>
<h3 id="-verbose-v"><code>--verbose</code>, <code>-v</code></h3>
<p><span class="md-typeset mdx-badge">
  <span class="mdx-badge__icon"><span class="twemoji"><svg xmlns="http://www.w3.org/2000/svg" width="1em" height="1em" viewBox="0 0 24 24"><path fill="currentColor" d="M14.4 6L14 4H5v17h2v-7h5.6l.4 2h7V6z"/></svg></span></span>
  <span class="mdx-badge__text">Flag</span>
</span>
Enable verbose output. (<code>DEBUG</code> level)</p>
<h3 id="-quiet-q"><code>--quiet</code>, <code>-q</code></h3>
<p><span class="md-typeset mdx-badge">
  <span class="mdx-badge__icon"><span class="twemoji"><svg xmlns="http://www.w3.org/2000/svg" width="1em" height="1em" viewBox="0 0 24 24"><path fill="currentColor" d="M14.4 6L14 4H5v17h2v-7h5.6l.4 2h7V6z"/></svg></span></span>
  <span class="mdx-badge__text">Flag</span>
</span>
Suppress output during build.</p>
<h3 id="-help"><code>--help</code></h3>
<p><span class="md-typeset mdx-badge">
  <span class="mdx-badge__icon"><span class="twemoji"><svg xmlns="http://www.w3.org/2000/svg" width="1em" height="1em" viewBox="0 0 24 24"><path fill="currentColor" d="M14.4 6L14 4H5v17h2v-7h5.6l.4 2h7V6z"/></svg></span></span>
  <span class="mdx-badge__text">Flag</span>
</span>
Show this message and exit.</p>

MkCliDoc
╰── MkHeader('`--help`', level=3)
╰── MkMaterialBadge('mdi:flag', 'Flag')

Bases: MkTemplate

init ¶

__init__(
    target: str | ArgumentParser | None = None,
    *,
    prog_name: str | None = None,
    show_hidden: bool = False,
    show_subcommands: bool = False,
    **kwargs: Any
)

Parameters:

Name	Type	Description	Default
`target`	`str \| ArgumentParser \| None`	Dotted path to click group / typer instance / ArgumentParser	`None`
`prog_name`	`str \| None`	Program name	`None`
`show_hidden`	`bool`	Show commands and options that are marked as hidden.	`False`
`show_subcommands`	`bool`	List subcommands of a given command.	`False`
`kwargs`	`Any`	Keyword arguments passed to parent	`{}`

Name	Children	Inherits
MkTemplate mknodes.templatenodes.mktemplate Node representing a jinja template.	MkCliDoc MkMaterialBadge MkImageCompare MkImageSlideshow MkIFrame MkCard MkInstallGuide MkCodeOfConduct MkCommitConventions MkPullRequestGuidelines MkDevEnvSetup ...	MkContainer

graph TD
  94721308870576["mkclidoc.MkCliDoc"]
  94721308869584["mktemplate.MkTemplate"]
  94721311697232["mkcontainer.MkContainer"]
  94721308848336["mknode.MkNode"]
  94721311766592["node.Node"]
  140564252373184["builtins.object"]
  94721308869584 --> 94721308870576
  94721311697232 --> 94721308869584
  94721308848336 --> 94721311697232
  94721311766592 --> 94721308848336
  140564252373184 --> 94721311766592

/home/runner/work/mknodes/mknodes/mknodes/basenodes/mkclidoc/metadata.toml

[metadata]
icon = "mdi:api"
name = "MkCliDoc"

[examples.cli]
title = "MkDocs-MkNodes CLI"
jinja = """
{{ "mkdocs_mknodes.cli:cli" | MkCliDoc }}
"""

[examples.sub_command]
title = "SubCommand"
jinja = """
{{ "mkdocs_mknodes.cli:cli" | MkCliDoc(prog_name="build") }}
"""

[examples.argparse]
title = "ArgumentParser"
python = """
from git_changelog import cli
import mknodes as mk

parser = cli.get_parser()
mk.MkCliDoc(parser)
"""

[fragments]
param_template = """
{{ param.opt_str | MkHeader(level=3) }}

{% if param.required %}
"{{ "REQUIRED" | md_style(bold=True) }}"
{% endif %}
{% if param.envvar %}
Environment variable{{ param.envvar }}
{% endif %}
{% if param.multiple %}
{{ "Multiple values allowed." | md_style(bold=True) }}
{% endif %}
{% if param.default %}
{{ "Default:" | md_style(bold=True) }} {{ param.default }}
{% endif %}
{% if param.is_flag %}
{{ "mdi:flag" | MkMaterialBadge("Flag") }}
{% endif %}
{% if param.help %}
{{ param.help }}
{% endif %}
"""
command_template = """
{{ info.name | MkHeader }}

{{ info.description }}

{{ info.usage | MkCode }}

{% for param in info.params %}
{{ "fragments/param_template" | render_template(param=param) }}

{% endfor %}

"""

[output.markdown]
template = """
{% if node.info %}
{{ "fragments/command_template" | render_template(info=node.info) }}
{% if node.show_subcommands %}
{% for sub_info in node.info.subcommands.values() %}
{{ "fragments/command_template" | render_template(info=sub_info) }}
{% endfor %}
{% endif %}
{% endif %}
"""

mknodes.basenodes.mkclidoc.MkCliDoc
class MkCliDoc(mktemplate.MkTemplate):
    """Node for showing documentation for click / typer CLI apps."""

    ICON = "material/api"

    def __init__(
        self,
        target: str | argparse.ArgumentParser | None = None,
        *,
        prog_name: str | None = None,
        show_hidden: bool = False,
        show_subcommands: bool = False,
        **kwargs: Any,
    ):
        r"""Constructor.

        Args:
            target: Dotted path to click group / typer instance / ArgumentParser
            prog_name: Program name
            show_hidden: Show commands and options that are marked as hidden.
            show_subcommands: List subcommands of a given command.
            kwargs: Keyword arguments passed to parent
        """
        super().__init__("output/markdown/template", **kwargs)
        self.target = target
        self.prog_name = prog_name
        self.show_hidden = show_hidden
        self.show_subcommands = show_subcommands

    @property
    def info(self) -> clinspector.CommandInfo | None:
        import importlib

        match self.target:
            case str():
                module, command = self.target.split(":")
                prog_name = self.prog_name
                mod = importlib.import_module(module)
                instance = getattr(mod, command)
            case None:
                if cli_eps := self.ctx.metadata.entry_points.get_group("console_scripts"):
                    module, command = cli_eps[0].value.split(":")
                    prog_name = cli_eps[0].name
                    mod = importlib.import_module(module)
                    instance = getattr(mod, command)
                else:
                    return None
            case _:
                instance = self.target
                prog_name = self.prog_name
        return clinspector.get_cmd_info(instance, command=prog_name)

MkCliDoc

Node for showing documentation for click / typer CLI apps.¶

Example: MkDocs-MkNodes CLI¶

MkNodes¶

--install-completion¶

--show-completion¶

--help¶

Example: SubCommand¶

build¶

--repo-url, -r¶

--build-fn, -b¶

--site-dir, -d¶

--clone-depth, -c¶

--config-path, -p¶

--theme, -t¶

--strict, -s¶

-u, --use-directory-urls¶

--verbose, -v¶

--quiet, -q¶

--help¶

__init__ ¶

`--install-completion`¶

`--show-completion`¶

`--help`¶

`--repo-url`, `-r`¶

`--build-fn`, `-b`¶

`--site-dir`, `-d`¶

`--clone-depth`, `-c`¶

`--config-path`, `-p`¶

`--theme`, `-t`¶

`--strict`, `-s`¶

`-u`, `--use-directory-urls`¶

`--verbose`, `-v`¶

`--quiet`, `-q`¶

`--help`¶

init ¶